Конфигурирование агента

Формат конфигурационного файла

Для настройки логики работы Solar TI Feeds необходимо внести изменения в конфигурационный файл. Путь к этому файлу необходимо указать при запуске агента. При поставке агента готовым дистрибутивом путь до конфига прописан в файле docker-compose.yml в виде volume.

Конфигурационный файл агента представлен в формате pkl. Благодаря использованию данного языка в агенте есть возможность создавать динамические конфигурации, наполняя конфигурационный файл логикой, присущей языкам программирования, а также есть возможность описывать структуру конфига, наследовать элементы и валидировать значения.

О языке PKL

PKL — это язык программирования для создания динамических конфигураций. Он сочетает простоту декларативных форматов с безопасностью и выразительностью статической типизации.

Рекомендация: Перед работой ознакомьтесь с официальной документацией PKL и установите расширение для своей IDE для подсветки синтаксиса.

Структура конфигурации

Набор файлов для настройки агента включает:

1. agent.pkl – базовый файл конфигурации с описанием структур и возможных значений параметров, который предоставляется вместе с образом агента для того, чтобы у клиентов была возможность на его основе изменять основную конфигурацию, а также для корректной работы IDE со структурами агента.
2. Основной конфигурационный файл в формате pkl – файл, который описывает логику работы и параметры запуска агента на основе определенных в базовом файле структур. Далее будет рассматриваться только основной конфигурационный файл, так как базовый тесно связан с кодом агента и не подлежит изменению.
3. templates.pkl – файл с шаблонами конфигурации.

Структура основного файла

// 1. Блок импортов и наследования
import "agent.pkl"

// 2. Локальные переменные (опционально)
local myVariable = "value"

// 3. Секция pipelines - описание цепочек обработки данных
pipelines {
  new Components.Pipeline { ... }
}

// 4. Секция settings - общие настройки агента
settings { ... }

Основная логика конфигурации — создание одной или нескольких цепочек (pipeline) обработки данных. Каждая цепочка состоит из компонентов, связанных между собой: начинается с input (источник данных), может включать transform (преобразования) и заканчивается sink (выходной приемник).

Секция Pipelines

В блоке pipelines объявляется listing (объект в pkl, список, по форме объявления напоминающий объект) pipeline, где можно указывать любое количество отдельных пайплайнов, каждый из которых состоит из компонент агента, описанных выше, представленных следующими блоками:

Параметр	Тип	Обязательность	Описание
name	String	Да	Уникальное имя пайплайна.
inputs	Listing	Да	Список компонентов-источников данных (генераторов).
transforms	Listing	Нет	Список компонентов-преобразователей (фильтры, мапперы).
sinks	Listing	Да	Список компонентов-приемников данных (выходные ноды).

Каждый компонент в пайплайне (input, transform, sink) содержит общий набор параметров:

Параметр	Тип данных	Обязательность	Описание	Пример
name	String	Да	Уникальное имя объекта компонента, задается пользователем	example-name
Inputs	Listing	Да, кроме input	Перечисление имен других компонент, которые будут являться источником данных для текущего элемента	inputs{“ example-name”}
sourceName	String	Нет	Имя исходника используемого компонента, по умолчанию определяется на основе класса компонента, требуется указывать только при создании нового компонента	sourceName = "indicator_generator"
outputBufferSize	UInt	Нет	Буфер сообщений для общения между компонентами	outputBufferSize = 5
threads	UInt	Нет	Количество потоков, по умолчанию = 1	threads = 5

Пример объявления структуры пайплайна без дополнительных параметров компонент:

pipelines {
  new Components.Pipeline{
    name = "example-pipeline"
    inputs {
      new agent.FeedsGenerator{
        name = "example-generator"
      }
    }
    transforms {
      new agent.IndicatorsTextMap{
        name = "example-map"
        inputs {
          "example-generator"
        }
      }
    }
    sinks {
      new agent.IndicatorsTextSink{
        name = "example-sink"
        inputs {
          "example-map"
        }
      }
    }
  }
}

Секция Settings

Блок settings содержит общие настройки работы агента, не связанные напрямую с логикой пайплайнов.
Параметры блока Settings:

Параметр	Тип данных	Обязательность	Описание	Пример
logger	LoggerConfig	Да	Параметры логирования	logger { logLevel = "info" logFormat = "json" enableConsole = true fileParams { directory = outputDir name = "agent.log" }}
healthCheck	HelthcheckConfig	Нет	Параметры сервера доступности	healthCheck { host = "localhost" port = 82}|
metrics	MetricsConfig	Нет	Параметры сервера метрик	metrics {serviceName = "agent"}
gracefulShutdownDelay	Duration	Нет	Таймаут обработки данных при завершении работы агента, значение по умолчанию 15.s	600.s

Пример блока настроек:

settings {
  gracefulShutdownDelay = 600.s
  logger {
    logLevel = "info"
    logFormat = "json"
    enableConsole = true
    fileParams {
      directory = logDir
      name = "agent.log"
    }
  }
  healthCheck {
  }
  metrics {
    serviceName = "agent"
  }
}

Детальная конфигурация Logger

Параметры конфигурации настроек логирования LoggerConfig:

Параметр	Тип данных	Значение по умолчанию	Обязательность	Описание	Пример
logLevel	String	info	Нет	Уровень логирования, возможные значения: error, warn, info, debug, trace	debug
enableConsole	Boolean	True	Нет	Вывод логов в консоль	false
logFormat	String	Json	Нет	Формат логов, возможные значения: plain, json	plain
fileParams	WriteFileParams		Нет	Настройки записи лога в файл	fileParams { directory = outputDir name = "agent.log"}

Параметры конфигурации настроек записи лога в файл WriteFileParams:

Параметр	Тип данных	Значение по умолчанию	Обязательность	Описание
directory	String		Нет	Директория для записи логов
name	String		Нет	Имя файла лога
maxSize	DataSize	100.mb	Нет	Максимальный размер файла лога для ротации
maxBackups	Int	5	Нет	Максимальное количество файлов лога
maxAge	Int	7	Нет	Срок жизни лога в днях

Детальная конфигурация HealthCheck

Параметры конфигурации сервера проверки доступности HealthCheck:

Параметр	Тип данных	Значение по умолчанию	Обязательность	Описание	Пример
host	String		нет	Адрес локального сервера	localhost
port	UInt	82	Нет	Порт локального сервера	8082

Детальная конфигурация Metrics

Параметры конфигурации сервера отдачи метрик MetricsConfig:

Параметр	Тип данных	Значение по умолчанию	Обязательность	Описание	Пример
host	String		Нет	Адрес локального сервера	localhost
port	UInt	8090	Нет	Порт локального сервера	8082
path	String	/metrics	Нет	Путь метрик на сервере	/api/metrics
serviceName	String		Нет	Имя сервиса	solar-agent

Параметры конфигурации встроенных объектов конфигураций агента

Конфигурации компонент пайплайнов

Параметры конфигурации ServerCfg

Параметр	Тип данных	Значение по умолчанию	Обязательность	Описание
apiToken	String		Да	JWT токен доступа к API
apiServerAddr	String		Да	Адрес сервера API TI Feeds на получение фидов
notificationServerAddr	String		Нет	Адрес сервера API TI Feeds на получение уведомлений по фидам
telemetryServerAddr	String		Нет	Адрес сервера API TI Feeds на отправку телеметрии
insecureSkipVerify	Boolean	false	Нет	Отключение проверки SSL-сертификата сервера

Параметры конфигурации ScheduleCfg

Параметр	Тип данных	Значение по умолчанию	Обязательность	Описание	Пример
useEvents	Boolean	false	Нет	Запуск агента по получению событий от сервера
useCron	Boolean	false	Нет	Запуск агента по cron
runOnStart	Boolean	true	Нет	Запуск агента при первом запуске вне зависимости от cron
crontab	String		Нет	Crontab периодичности запуска агента	"*/1 * * * *"

Параметры конфигурации SQLiteCfg

Параметр	Тип данных	Обязательность	Описание
sqliteDbFile	String	Да	Путь до файла БД, в который сохраняется состояние работы агента

Параметры конфигурации IterParams

Параметр	Тип данных	Значение по умолчанию	Обязательность	Описание	Пример
direction_sort	String	ASC	Нет	Порядок сортировки и итерации фидов, возможные значения: ASC, DESC	DESC
limit	Int	1000	Нет	Ограничение количества индикаторов в ответе на запрос, максимум 10000	10000

Параметры конфигурации IndicatorRequestParams

Параметр	Тип данных	Обязательность	Описание	Пример
feedNames	List	Нет	Список запрашиваемых фидов	List("TOR","VPN","PHISHING","C2","APT","MALWARE")
types	List	Нет	Список типов запрашиваемых индикаторов, возможные значения: "domain-name", "ipv4-addr", "ipv6-addr", "socketv4", "url", "md5-hash", "sha1-hash", "sha256-hash"	List("ipv4-addr", "ipv6-addr", "socketv4", "domain-name", "url")
actions	List	Нет	Список запрашиваемых action, возможные значения: "create", "update", "delete"	List("create", "update", "delete")
fields	List	Нет	Список запрашиваемых полей индикаторов, возможные значения: "indicator_id", "indicator_type", "action", "value", "description", "first_seen", "last_seen", "valid_until", "external_references", "rules", "categories", "sources", "relations", "feeds", "zone"	List("value”, "zone")
Iter	IterParams	Нет	Параметры итерации	iter {limit = 1000}

Параметры конфигурации DomainsCategoriesRequestParams

Параметр	Тип данных	Обязательность	Описание	Пример
Iter	IterParams	Нет	Параметры итерации	iter {limit = 1000}

Параметры конфигурации FileWriterConfig

Параметр	Тип данных	Значение по умолчанию	Обязательность	Описание
outputDirectory	Srting		Да	Директория для записи
outputFileName	Srting		Да	Имя файла
writeMode	Srting		Да	Режим записи, возможные значения: append, replace, rolling
fileFormat	Srting		Да	Формат файла, возможные значения: txt, csv
writeHeaders	Boolean	True	Нет	Записывать ли заголовки в CSV файл
separator	Srting	,	Нет	Разделитель в CSV
quote	Srting	”	Нет	Символ кавычки в CSV
allQuotes	Boolean	False	Нет	Принудительное экранирование всех ячеек CSV

Параметры конфигурации для Generator

Генераторы агента — это входные компоненты пайплайна (типа input), отвечающие за получение данных от сервера TI Feeds и имеющие следующие ключевые функции:

• Выполняют запросы к внешним источникам данных.
• Регулируют периодичность и время запуска.
• Сохраняют и используют состояние между запусками (опционально).

Состояние генератора
Каждый генератор отслеживает своё состояние, которое включает:

• UUID — уникальный идентификатор
• Имя генератора
• Тип обрабатываемого индикатора
• Режим работы (cron по расписанию или event по событию)

Состояние хранится в базе данных SQLite. Для доступа к состоянию необходимо указать путь к БД через параметр sqlite.

Конфигурация
Все генераторы наследуют базовые параметры конфигурации из общей структуры AgentGenerator.

В таблице описаны параметры конфигурации для AgentGenerator:

Параметр	Тип данных	Описание	Пример
server	ServerCfg	Конфигурация подключения к серверу TI Feeds. Базовый адрес (указывается без https/http)	server = new agent.ServerCfg { apiToken = read("env:TIC_AGENT_API_TOKEN") apiServerAddr = read("env:TIC_AGENT_API_SERVER") insecureSkipVerify = true }
schedule	ScheduleCfg	Конфигурация режимов запуска генератора	schedule = new agent.ScheduleCfg { useCron = true runOnStart = true crontab = "*/5 * * * *" }
sqlite	SQLiteCfg	Конфигурация базы SQLite	sqlite = new agent.SQLiteCfg { sqliteDbFile = read("env:TIC_AGENT_SQLITE_DB_FILE") }

Параметры конфигурации для AgentIndicatorsGenerator

Базовая надстройка для генераторов, специализирующихся на получении индикаторов. К общим параметрам настройки режимов работы генератора и адресов сервера TI добавляются параметры для точной настройки необходимых данных при запросе индикаторов.

Параметр	Тип данных	Описание	Пример
filter	IndicatorsRequestParams	Параметры запросов индикаторов	filter = new agent.IndicatorRequestParams { types = List("ipv4-addr", "ipv6-addr", "socketv4" "domain-name", "url") feedNames = feedsList actions = List("create", "update", "delete") fields = List("indicator_id", "value", "indicator_type", "valid_until", "first_seen", "action", "external_references", "categories", "last_seen", "relations", "description", "rules", "feeds", "zone") iter { limit = 1000 } }
processTimeout	Duration	Время ожидания обработки индикаторов агентом, для синхронизации между sink и generator при записи в файл	10.s

IndicatorsGenerator

Конечная реализация генератора для получения индикаторов из эндпоинтов /indicators/{indicatorType}. Используется конфигурация AgentIndicatorsGenerator.
Параметр types определяет выбор эндпоинта для запроса, при указании нескольких типов индикаторов выполняется соответствующее количество запросов к каждому из них, включая постраничную итерацию. Параметр feedNames не используется. Имя компонента для объявления в пайплайне:
sourceName = “indicator_generator”

FeedsStreamGenerator

Конечная реализация генератора для получения индикаторов конкретного фида из эндпоинтов /feeds/{feedName}.
Используется конфигурация AgentIndicatorsGenerator.
Параметр types определяет выбор типов индикаторов в параметрах запросов.
Параметр feedNames определяет выбор эндпоинта feedName для запроса, при указании нескольких фидов выполняется соответствующее количество запросов к каждому из них, включая постраничную итерацию.
Позволяет выгрузить несколько независимых наборов фидов, в связи с этим возможны дубликаты индикаторов при пересечении выгружаемых множеств. Имя компонента для объявления в пайплайне:
sourceName = “feed_stream_generator”

FeedsGenerator

Конечная реализация генератора для получения индикаторов конкретного фида из эндпоинта /feeds.
Используется конфигурация AgentIndicatorsGenerator.
Параметр types определяет выбор типов индикаторов в параметрах запросов.
Параметр feedNames определяет выбор перечень имен фидов для запроса, при указании нескольких фидов выполняется один запрос со всеми указанными параметрами фидов. включая постраничную итерацию.
Позволяет работать с древовидным представлением фидов. Имя компонента для объявления в пайплайне:
sourceName = “feed_generator”

Параметры конфигурации для DomainCategoriesGenerator

Генератор, специализирующихся на получении категорий доменов.
К общим параметрам настройки режимов работы генератора и адресов сервера TI добавляются параметры для точной настройки необходимых данных при запросе категорий доменов.
Параметры конфигурации для DomainCategoriesGenerator:

Параметр	Тип данных	Описание	Пример
filter	DomainCategoriesRequestParams	Параметры запроса категорий доменов	filter { iter { limit = 1000 } }

Параметры конфигурации для Map

Параметры конфигурации для AgentFilter

Компонент имеет один единственный параметр code, в котором описывается условие фильтрации на основе структуры объекта данных.

Параметры конфигурации для AgentFilter:

Параметр	Тип данных	Описание	Пример
code	String	Условие фильтрации на основе полученных полей индикатора. Список полей индикатора аналогичен конфигурации Map	json code = ''' Zone == \\\”BLACK\\\” '''

IndicatorsFilter

Конечная реализация фильтра для индикаторов. Используется конфигурация AgentFilter. Имя компонента для объявления в пайплайне:
sourceName = “indicators_filter”

DomainCategoriesFilter

Конечная реализация фильтра для категорий доменов. Используется конфигурация AgentFilter. Имя компонента для объявления в пайплайне:
sourceName = “domain_categories_filter”

Параметры конфигурации для AgentTextMap

Компонент имеет один единственный параметр fields_map, в котором описывается маппинг структуры индикатора на столбцы CSV / TXT файла.
Для преобразования данных используется язык запросов expr-lang.
Параметры конфигурации для AgentTextMap:

Параметр	Описание	Пример
fieldsMap	Маппинг полученных полей объекта на выходные данные в CSV / TXT файле. Промежуточные результаты сохраняются в json, в котором в качестве ключа выступает название желаемого столбца данных, а в качестве значения - выражение на expr для преобразования исходного значения. Список свойств для обработки в expr указан ниже для конкретной реализации	json fieldsMap = """\{"value": "Value"\} \"""

IndicatorsTextMap

Конечная реализация map для индикаторов. Используется конфигурация AgentTextMap. Имя компонента для объявления в пайплайне:
sourceName = “indicators_text_map”

Параметры индикатора в рамках expr

Список возможных свойств индикатора в выражениях из expr:

Свойство индикатора	Тип данных	Значение
IndicatorID	string	UUID
IndicatorType	string	ipv4-addr, ipv6-addr, socketv4, domain-name, url
Action	string	CREATE, UPDATE, DELETE
UpdatedAt	uint64	unix timestamp with microseconds, время модификации индикатора
Value	string	Значение индикатора
Description	string	Описание
FirstSeen	uint64	unix timestamp with microseconds
LastSeen	uint64	unix timestamp with microseconds
ValidUntil	uint64	unix timestamp with microseconds
Relations.ObjectID	string	stix-like uuid
Relations.ObjectType	string	Тип объекта связи: indicator, report, malware, threat-actor, tool
Relations.IndicatorType	string	Тип индикатора, если object_type - indicator: ipv4-addr, ipv6-addr, socketv4, domain-name, url
Relations.ObjectValue	string	Значение объекта связи
ExternalReferences	[]string	Ссылки на внешние источники
Rules	[]string	Сработавшие детектирующие правила
Categories	[]string	Категории индикатора
Zone	string	Зона индикатора

DomainCategoriesTextMap

Конечная реализация map для категорий доменов. Используется конфигурация AgentTextMap. Имя компонента для объявления в пайплайне:
sourceName = “domain_categories_text_map”

Параметры категории доменов в рамках expr

Список возможных свойств индикатора в выражениях из expr:

Свойство	Тип данных	Значение
FQDN	string	Значение домена
OriginalFQDN	string	Оригинальное значение домена
Categories	string	Массив категорий вида: ID – id категории Name – имя категории Description – описание категории GroupName – имя группы GroupID – id группы
UpdatedAt	uint64	unix timestamp with microseconds, время модификации
LastCategorizedAt	uint64	unix timestamp with microseconds, время последней категоризации

Дополнительные функции expr

Также набор функции expr-lang расширен следующим набором функций:

• timeFromUnixMicro (timeVal uint64) → time - преобразование unix timestamp в формат time.
• floatToInt(value float32) → int - преобразование числа с плавающей точкой в целочисленный формат.
• formatUnixTime (timeVal uint64, layout string) → string - преобразование unix timestamp к требуемому строковому формату отображения. Возможные значения layout:

• Layout
• ANSIC
• UnixDate
• RubyDate
• RFC822
• RFC822Z
• RFC850
• RFC1123
• RFC1123Z
• RFC3339
• RFC3339Micro
• RFC3339Nano
• Kitchen
• Stamp
• StampMilli
• StampMicro
• StampNano
• DateTime
• DateOnly
• TimeOnly

csv title="Пример CSV файла после маппинга полей:"
Action,AdditionalInformation,Description,Expiration,FirstSeen,IOCName,IOCType,Status,TI_ReportID,Type,URLlink
new,Categories:  LastSeen: 1970-01-01 03:00:00 +0300 MSK,,5024-03-25 14:34:46 +0300 MSK,2024-03-25 14:35:23 +0300 MSK,2001:1838:6000::,ipv6-addr,0.000000,relevant,cert,,feed,

Параметры конфигурации для Sink

Все sink агента имеют базовую конфигурацию AgentSink.
Параметры конфигурации для AgentSink:

Параметр	Тип	Описание
sqlite	SQLiteCfg	Конфигурация базы SQLite

Параметры конфигурации для AgentTextSink

Базовая конфигурация Sink агента для записи данных в файл. Параметры конфигурации для AgentTextSink:

Параметр	Тип	Описание	Пример
writer	FileWriterCfg	Конфигурация формата записи в файл	writer { outputDirectory = outputDir outputFileName = ouptputFileName writeMode = "rolling" fileFormat = "csv" writeHeaders = true separator = "," quote = "\"" allQuotes = true }
pusher	ServiceConfig	Конфигурация сервиса доставки данных во внешнюю систему для интеграции	pusher = new agent.CyberTraceCfg { address { host = cyberTraceHost port = cyberTracePort insecureSkipVerify = true scheme = "https" } credentials = new agent.Basic { username = cyberTraceUser password = cyberTracePassword } timeout = 20.s listName = "4rays_list" confidence = 80 retention = 518400.min enableBinaryErrorSearch = true }

Компонент записывает полученные индикаторы в выходной файл в формате CSV / TXT и имеет 3 режима работы:

1. replace - каждый раз перезаписывает выходной файл;
2. append - добавляет полученные индикаторы в существующий файл;
3. rolling - записывает полученные индикаторы в новый файл с timestamp'ом в названии ({output_file_name}_1725962880.csv).

Поддерживаются 2 формата файлов:

1. CSV - используется для сохранения индикаторов с соответствующими заголовками;
2. TXT - используется для сохранения индикаторов.

Cостояния генераторов сохраняются в базу данных SQLite. При использовании generator'a и sink'a в рамках одного пайплайна в обоих компонентах должен совпадать путь до файла SQLite. Также в рамках AgentTextSink есть возможность определить параметры объекта для доставки индикаторов до систем, интеграция с которыми поддерживается агентом. Если параметры не указаны, то доставка индикаторов не осуществляется.

IndicatorsTextSink

Конечная реализация sink для записи индикаторов в файл. Используется конфигурация AgentTextSink. Имя компонента для объявления в пайплайне:
sourceName = “indicators_text_sink”

DomainsTextSink

Конечная реализация sink для записи категорий доменов в файл. Используется конфигурация AgentTextSink. Имя компонента для объявления в пайплайне:
sourceName = “domains_text_sink”

Параметры конфигурации для TicKafkaSink

Компонент записывает полученные данные в указанные топики kafka. Поддерживаются объекты индикаторов, категорий доменов, а также их версии после обработки map.

Параметры конфигурации TicKafkaSink

Параметр	Описание	Пример
kafka	Параметры Kafka	kafka = new Sinks.Kafka { name = "placeholder" inputs { "placeholder"} common { brokers {read("env:TIC_AGENT_KAFKA_BROKERS")} topics {read("env:TIC_AGENT_KAFKA_TOPIC")} saslAuth { saslMechanism = read("env:TIC_AGENT_KAFKA_SASL_MECHANISM") as Common.SASLMechanism saslUsername = read("env:TIC_AGENT_KAFKA_SASL_USERNAME") saslPassword = read("env:$TIC_AGENT_KAFKA_SASL_PASSWORD$") } } }
keyField	Имя поля, которое будет использоваться в качестве ключа при записи сообщения в Kafka	fqdn

Имя компонента для объявления в пайплайне:
sourceName = “tic_kafka_sink”

Параметры конфигурации для sink Kafka

Параметр	Тип данных	Значение по умолчанию	Обязательность	Описание	Пример
common	Common.Kafka		Да	Базовая конфигурация подключения к Kafka	common { brokers {read("env:TIC_AGENT_KAFKA_BROKERS")} topics {read("env:TIC_AGENT_KAFKA_TOPIC")} saslAuth { saslMechanism = read("env:TIC_AGENT_KAFKA_SASL_MECHANISM") as Common.SASLMechanism saslUsername = read("env:TIC_AGENT_KAFKA_SASL_USERNAME") saslPassword = read("env:$TIC_AGENT_KAFKA_SASL_PASSWORD$") } }
maxRequestSize	DataSize	10.mib	Нет	Максимальный размер сообщения
lingerMs	Duration	0.ms	Нет	Максимальный период формирования batch для отправки сообщений
batchNumMessages	Int	100000	Нет	Размер batch в сообщениях

Параметры конфигурации Common.Kafka

Параметр	Тип данных	Обязательность	Описание
saslAuth	KafkaAuth	Да	Настройки аутентификации
brokers	Listing	Да	Адрес брокеров kafka
version	String	Нет	Версия
topics	Listing	Да	Список топиков kafka

Параметры конфигурации для аутентификации при подключении к серверу Kafka (KafkaAuth)

Параметр	Тип данных	Обязательность	Описание
saslMechanism	String	Да	Механизм SASL, возможные значения: SCRAM-SHA-512, SCRAM-SHA-256
saslUsername	String	Да	Имя пользователя
saslPassword	String	Да	Пароль